IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Vk / VkVisual.z / VkVisual

Wrap

Text File | 2002-10-03 | 51.0 KB | 1,255 lines

_V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) NNNNAAAAMMMMEEEE VVVVkkkkVVVViiiissssuuuuaaaallll - convenience class for dealing with X11 visuals HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <Vk/VkVisual.h> PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss,,,, DDDDeeeessssttttrrrruuuuccccttttoooorrrr VkVisual (Widget w = _N_U_L_L, Boolean forceNewCmap=_F_A_L_S_E) VkVisual (const VkComponent *component, Boolean forceNewCmap=_F_A_L_S_E) VkVisual (int visualClass, int level=_N_O_R_M_A_L__L_E_V_E_L, int colors=_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S, CARD32 xparentRequested=_T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E, Boolean forceNewCmap=_F_A_L_S_E) VkVisual (const _V_k_V_i_s_u_a_l&) VkVisual &operator =(const _V_k_V_i_s_u_a_l&) virtual ~VkVisual() CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkVisual (VkScreen *screen, int visualClass, int level=_N_O_R_M_A_L__L_E_V_E_L, int colors=_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S, CARD32 xparentRequested=_T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E, Boolean forceNewCmap=_F_A_L_S_E) SSSSeeeettttttttiiiinnnngggg tttthhhheeee CCCCllllaaaassssssss'''' VVVViiiissssuuuuaaaallll IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn virtual Colormap setColormap(Colormap cmap=_N_U_L_L, Boolean setDefault=_F_A_L_S_E) virtual void setVisual (Widget w = _N_U_L_L, Boolean forceNewCmap=_F_A_L_S_E) virtual void setVisual (const VkComponent *component, Boolean forceNewCmap=_F_A_L_S_E) virtual VkVisual::status setVisual (int visualClass, int level, int colors, CARD32 transparent, Boolean forceNewCmap=_F_A_L_S_E) PPPPaaaaggggeeee 1111 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) DDDDaaaattttaaaa AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss virtual int argCnt() const virtual ArgList argList() const virtual void argList(Arg *args, Cardinal *offset) const inline void argList(Arg *args, int *offset) const const char *className( void ) const virtual Colormap colormap() const virtual Boolean colormapCreated() const virtual int depth() const virtual int maxLevel() const virtual int minLevel() const virtual int numColors() const virtual Visual *visual() const virtual VisualID visualID() const virtual const VkVisualInfo *vkVisualInfo ( VisualID vis) const virtual const VkVisualInfo *vkVisualInfo ( Visual *vis=_N_U_L_L) const virtual const VkVisualInfo *vkVisualInfo ( const Widget w) const virtual const VkVisualInfo *vkVisualInfo ( int index) const virtual Window window() const DDDDeeeebbbbuuuuggggggggiiiinnnngggg FFFFuuuunnnnccccttttiiiioooonnnnssss virtual const char *indexString(index) const virtual const char *planesString(planes) const virtual void printAll() const virtual void print( ) const virtual void print( VisualID vid) const virtual void print( const Visual *vis) const virtual void print( const Widget w) const PPPPaaaaggggeeee 2222 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) virtual void print( int index) const virtual void print( const VkVisualInfo *vis) const virtual const char *statusString(status) const virtual const char *transparencyString(transparency) const virtual const char *visualClassString(int) const SSSSttttaaaattttiiiicccc FFFFuuuunnnnccccttttiiiioooonnnnssss static Widget visualParent( Widget w, Visual ** ) static void visualParentArgs(Widget parent, Arg *args, int *cnt) EEEEnnnnuuuummmmssss enum colors {_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S} enum index {_R_E_S_E_T, _F_I_R_S_T, _N_E_X_T, _L_A_S_T} enum planes {_N_O_R_M_A_L__L_E_V_E_L, _O_V_E_R_L_A_Y__L_E_V_E_L, _U_N_D_E_R_L_A_Y__L_E_V_E_L, _M_A_X__O_V_E_R_L_A_Y__L_E_V_E_L, _M_I_N__O_V_E_R_L_A_Y__L_E_V_E_L, _M_A_X__U_N_D_E_R_L_A_Y__L_E_V_E_L, _M_I_N__U_N_D_E_R_L_A_Y__L_E_V_E_L, _A_N_Y__L_E_V_E_L} enum status {_F_A_I_L_U_R_E, _S_U_C_C_E_S_S, _A_L_M_O_S_T} enum transparency {_T_R_A_N_S_P_A_R_E_N_T__N_O_N_E, _T_R_A_N_S_P_A_R_E_N_T__P_I_X_E_L, _T_R_A_N_S_P_A_R_E_N_T__M_A_S_K, _T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E} CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Dealing with the interaction between widgets and X11 visuals can get complicated. Some applications either get it wrong, or else stick with the default visual when another would be more appropriate. Code, even library code, that assumes default visual attributes is commonplace. Such an assumption is especially bad in a library, because libraries must work with applications that use non-default visuals. _V_k_V_i_s_u_a_l() makes it easy for an application to set up the X11 visual information it needs. Using _V_k_V_i_s_u_a_l, it is easy to do such things as: +o get an existing widget's full visual information. +o to pick the best visual for a _S_h_e_l_l or for an entire application by describing its semantic characteristics. This includes such things as getting the "deepest overlay visual". PPPPaaaaggggeeee 3333 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) +o get information about the default visual. +o deal with actual visuals, default or non-default, in a consistent and robust way that works across different kinds of hardware. +o Get a suitable window for use when creating a GC or a pixmap. On an SGI workstation, Widget access to the popup or overlay bitplanes is by means of non-default X11 visuals. There are a few things that one needs to be careful of when using Xt widgets with non-default visuals. (For further information about X11 and Xt handling of visual information, see below.) The _V_k_V_i_s_u_a_l class simplifies this task. Because it simplifies the model, _V_k_V_i_s_u_a_l cannot do all possible things. Applications that have more complex needs than those addressed by _V_k_V_i_s_u_a_l will still need to use direct Xlib and/or OpenGL calls instead. The _V_k_V_i_s_u_a_l class itself deals with global things, such as: +o Associating a single colormap with a single visual +o Coordinating X11 visual information with that provided by the root window's _S_E_R_V_E_R__O_V_E_R_L_A_Y__V_I_S_U_A_L_S property. Each _V_k_V_i_s_u_a_l instance deals with all of the information pertinent to a single visual. The visual can be set to be: +o a caller-defined visual +o the same visual a specific widget is using +o the same visual a specific ViewKit component is using +o the default visual The visual information can also be reset to a new visual (using _s_e_t_V_i_s_u_a_l()), but all old visual information is then lost. If an application will continue to need to refer to both sets of visual information, it should create a second _V_k_V_i_s_u_a_l object, not just reset the first one. Information such as the colormap or the read-only ArgList are created as needed. Any such information is cached, and reused as appropriate. PPPPaaaaggggeeee 4444 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) VkVisual(VkComponent *comp, Boolean forceNewCmap=_F_A_L_S_E); Create a _V_k_V_i_s_u_a_l object whose visual attributes match those of _c_o_m_p->_b_a_s_e_W_i_d_g_e_t(). VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) VkVisual(Widget w=_N_U_L_L, Boolean forceNewCmap=_F_A_L_S_E); Create a _V_k_V_i_s_u_a_l object whose visual attributes match the widget's. If _w is _N_U_L_L, default visual information is set up. VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) VkVisual (int visualClass, int level=_N_O_R_M_A_L__L_E_V_E_L, int colors=_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S, CARD32 transparency=_T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E, Boolean forceNewCmap=_F_A_L_S_E) Create a _V_k_V_i_s_u_a_l object as close to the specified calling parameters as possible. For how "close" is determined, see the description of _s_e_t_V_i_s_u_a_l(), below. VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) ---- VVVViiiieeeewwwwKKKKiiiitttt 2222....1111 oooonnnnllllyyyy VkVisual (VkScreen *screen, int visualClass, int level=_N_O_R_M_A_L__L_E_V_E_L, int colors=_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S, CARD32 transparency=_T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E, Boolean forceNewCmap=_F_A_L_S_E) Create a _V_k_V_i_s_u_a_l object as close to the specified calling parameters as possible on the specified VkScreen. For how "close" is determined, see the description of _s_e_t_V_i_s_u_a_l(), below. VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) VkVisual (const VkVisual&) This is the copy constructor. VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) PPPPaaaaggggeeee 5555 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) VkVisual &operator =(const VkVisual&) This is the "operator =" constructor. ~~~~VVVVkkkkVVVViiiissssuuuuaaaallll(((()))) virtual ~VkVisual(); The destructor deletes the instance. Global information, such as a visual/colormap pairing, is undisturbed. eeeennnnuuuummmm ccccoooolllloooorrrrssss enum colors {_M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S} Using this for the number of colors in the constructor, or in a _s_e_t_V_i_s_u_a_l() call, means that the deepest visual that otherwise satisfies the request criteria is considered a match. eeeennnnuuuummmm iiiinnnnddddeeeexxxx enum index {_R_E_S_E_T, _F_I_R_S_T, _N_E_X_T, _L_A_S_T} This is passed to _v_k_V_i_s_u_a_l_I_n_f_o(_i_n_t) or _p_r_i_n_t(_i_n_t) when using it to iterate over the visuals list. eeeennnnuuuummmm ppppllllaaaannnneeeessss enum planes {_N_O_R_M_A_L__L_E_V_E_L, _O_V_E_R_L_A_Y__L_E_V_E_L, _U_N_D_E_R_L_A_Y__L_E_V_E_L, _M_A_X__O_V_E_R_L_A_Y__L_E_V_E_L, _M_I_N__O_V_E_R_L_A_Y__L_E_V_E_L, _M_A_X__U_N_D_E_R_L_A_Y__L_E_V_E_L, _M_I_N__U_N_D_E_R_L_A_Y__L_E_V_E_L, _A_N_Y__L_E_V_E_L} This specifies which level bit planes are being requested. These constants do not conflict with any legitimate specific level. Calls to the constructor, or to _s_e_t_V_i_s_u_a_l(), can specify either the explicit level required or one of these enum values. NNNNOOOORRRRMMMMAAAALLLL____LLLLEEEEVVVVEEEELLLL - request for the normal planes OOOOVVVVEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - request for any overlay planes UUUUNNNNDDDDEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - any underlay planes MMMMAAAAXXXX____OOOOVVVVEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - highest available overlay level MMMMIIIINNNN____OOOOVVVVEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - lowest available overlay level PPPPaaaaggggeeee 6666 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) MMMMAAAAXXXX____UUUUNNNNDDDDEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - underlay level that is the closest to zero MMMMIIIINNNN____UUUUNNNNDDDDEEEERRRRLLLLAAAAYYYY____LLLLEEEEVVVVEEEELLLL - underlay level that is the furthest from zero AAAANNNNYYYY____LLLLEEEEVVVVEEEELLLL - don't care which level eeeennnnuuuummmm ssssttttaaaattttuuuussss enum status {_F_A_I_L_U_R_E, _S_U_C_C_E_S_S, _A_L_M_O_S_T} These are the values that _s_e_t_V_i_s_u_a_l() can return. It is up to an application to notice that it did not get _S_U_C_C_E_S_S, and make appropriate adjustments if it needs to. SSSSUUUUCCCCCCCCEEEESSSSSSSS - the visual found is exactly what was requested. AAAALLLLMMMMOOOOSSSSTTTT - the visual found is likely to be close enough. It is up to the application to query any attributes it cares about to see whether the attribute is acceptable. FFFFAAAAIIIILLLLUUUURRRREEEE - there was a serious problem, such as could not get the right visual class. This generally means that the default visual had to be assigned, rather than what was requested. The lowest status found in processing any of the parameters is returned. I.e. if anything failed, _F_A_I_L_U_R_E. Else if anything was _A_L_M_O_S_T, then that is returned. _S_U_C_C_E_S_S is returned only if everything succeeded. eeeennnnuuuummmm ttttrrrraaaannnnssssppppaaaarrrreeeennnnccccyyyy enum transparency {_T_R_A_N_S_P_A_R_E_N_T__N_O_N_E, _T_R_A_N_S_P_A_R_E_N_T__P_I_X_E_L, _T_R_A_N_S_P_A_R_E_N_T__M_A_S_K, _T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E} This is the kind of transparency that is requested. aaaarrrrggggCCCCnnnntttt(((()))) virtual int argCnt() const Returns the number of visual arguments that a call to _a_r_g_L_i_s_t() will supply. The number this returns could change in a future release. aaaarrrrggggLLLLiiiisssstttt(((()))) virtual ArgList argList() const Returns pointer to a read-only ArgList, suitable for using in an Xt call such as: _V_k_V_i_s_u_a_l vis (parent); XtSetValues( w, vis.argList(), vis.argCnt() ); PPPPaaaaggggeeee 7777 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) aaaarrrrggggLLLLiiiisssstttt(((()))) virtual void argList(Arg *args, Cardinal *offset) const Appends the visual arguments to the ArgList _a_r_g_s, beginning at position _o_f_f_s_e_t, and then increments the _o_f_f_s_e_t by the number of arguments it appended. aaaarrrrggggLLLLiiiisssstttt(((()))) inline void argList(Arg *args, int *offset) const An overloaded version of the previous call. This one takes an int* instead of a Cardinal* ccccllllaaaassssssssNNNNaaaammmmeeee(((()))) const char *className( void ) const The class name of _V_k_V_i_s_u_a_l is "VkVisual". ccccoooolllloooorrrrmmmmaaaapppp(((()))) virtual Colormap colormap() const Returns the colormap associated with this instance of _V_k_V_i_s_u_a_l. If there is no colormap, an empty sharable one will be created. ccccoooolllloooorrrrmmmmaaaappppCCCCrrrreeeeaaaatttteeeedddd(((()))) virtual Boolean colormapCreated() const Returns TRUE iff the current colormap was created by _V_k_V_i_s_u_a_l. This can be used by the application to tell whether or not the colormap should be destroyed when no longer needed. Failure to destroy colormaps that _V_k_V_i_s_u_a_l creates causes colormap leakage in the X server. Fortunately, from a practical point of view, most applications do not need to be concerned with this: +o All created colormaps are deleted when the application terminates. Unless a lot of colormaps are being created, this is adequate. +o _V_k_V_i_s_u_a_l reuses colormaps. Unless the application sets _f_o_r_c_e_N_e_w_C_o_l_o_r_m_a_p or uses _s_e_t_C_o_l_o_r_m_a_p(), there will be at most one colormap for each visual used. This is normally few enough that they can be ignored until they are destroyed when the application terminates. +o Any _V_k_V_i_s_u_a_l that is constructed by passing it a widget uses the colormap from that widget. Such a colormap should not be explicitly destroyed. PPPPaaaaggggeeee 8888 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) ddddeeeepppptttthhhh(((()))) virtual int depth() const Returns the depth associated with this instance's visual. iiiinnnnddddeeeexxxxSSSSttttrrrriiiinnnngggg(((()))) const char *indexString(planes) const Debug function: print (on stderr) the string equivalent to the passed enum value. mmmmaaaaxxxxLLLLeeeevvvveeeellll(((()))) virtual int maxLevel() const Returns the maximum framebuffer level for the current screen. mmmmiiiinnnnLLLLeeeevvvveeeellll(((()))) virtual int minLevel() const Returns the minimum framebuffer level for the current screen. nnnnuuuummmmCCCCoooolllloooorrrrssss(((()))) virtual int numColors() const Returns the number of colors in the colormap associated with this instance's visual. ppppllllaaaannnneeeessssSSSSttttrrrriiiinnnngggg(((()))) const char *planesString(planes) const Debug function: print (on stderr) the string equivalent to the passed enum value pppprrrriiiinnnntttt(((()))) void print() const Debug function: print (on stderr) the visual information from the _V_k_V_i_s_u_a_l instance. pppprrrriiiinnnntttt(((()))) void print(VisualID vid) const Debug function: print (on stderr) the visual information matching the Visual ID. PPPPaaaaggggeeee 9999 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) pppprrrriiiinnnntttt(((()))) void print(Visual *vis) const Debug function: print (on stderr) the visual information matching the X visual. pppprrrriiiinnnntttt(((()))) void print(Widget w) const Debug function: print (on stderr) the visual information matching the Widget. pppprrrriiiinnnntttt(((()))) void print(int index) const Debug function: print (on stderr) the visual information matching the VkVisual whose index is given. pppprrrriiiinnnntttt(((()))) void print(const VkVisualInfo *vis) const Debug function: print (on stderr) the visual information from _v_i_s. pppprrrriiiinnnnttttAAAAllllllll(((()))) void printAll() const Debug function: print (on stderr) a variety of details about the visuals of the current display. sssseeeettttCCCCoooolllloooorrrrmmmmaaaapppp(((()))) virtual Colormap setColormap(Colormap cmap=_N_U_L_L, Boolean setDefault=_F_A_L_S_E) If there is a passed-in colormap, makes it current. If there is no colormap, create a new empty one that matches the current visual. If _s_e_t_D_e_f_a_u_l_t is True, make the new colormap be the default one for the visual associated with this _V_k_V_i_s_u_a_l instance. Return the now- current colormap. sssseeeettttVVVViiiissssuuuuaaaallll(((()))) virtual void setVisual (Widget w = _N_U_L_L, Boolean forceNewCmap=_F_A_L_S_E) PPPPaaaaggggeeee 11110000 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) Resets the _V_k_V_i_s_u_a_l to the visual of the widget or gadget, or if _N_U_L_L then the default visual. If _f_o_r_c_e_N_e_w_C_m_a_p is true, you are guaranteed a new, empty, colormap. Otherwise, _V_k_V_i_s_u_a_l will reuse an existing colormap for this visual if one is available. Unless you know you need a new colormap, you should leave this _F_A_L_S_E. sssseeeettttVVVViiiissssuuuuaaaallll(((()))) virtual void setVisual (const VkComponent *component, Boolean forceNewCmap=_F_A_L_S_E) Resets the _V_k_V_i_s_u_a_l to the visual used by _c_o_m_p_o_n_e_n_t->_b_a_s_e_W_i_d_g_e_t(). If _f_o_r_c_e_N_e_w_C_m_a_p is true, you are guaranteed a new, empty, colormap. Otherwise, _V_k_V_i_s_u_a_l will reuse an existing colormap for this visual if one is available. Unless you know you need a new colormap, you should leave this _F_A_L_S_E. sssseeeettttVVVViiiissssuuuuaaaallll(((()))) virtual VkVisual::status setVisual (int visualClass, int level, int colors, CARD32 transparent, Boolean forceNewCmap=_F_A_L_S_E) Resets the visual to be as close to the specified calling parameters as possible. This function always sets _s_o_m_e visual. It will set the default visual, if there is no better match. +o visualClass - must be one of the constants from <X11/X.h> (StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor). If the application asks for a class that is not supported by the current screen, _s_e_t_V_i_s_u_a_l() returns _F_A_I_L_U_R_E and provides the default visual. +o level - _s_e_t_V_i_s_u_a_l() always tries to give you the type of planes you asked for (i.e. a specific level, overlay planes, underlay planes, or normal planes). If the value is one of the enum constants, that is used. Else if the value is greater than the maximum level, then the maximum level is used. Else if the value is less than the minimum level, then the minimum level is used. Else the value is a legal explicit level and it is used directly. PPPPaaaaggggeeee 11111111 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) If the requested plane(s) exist for the specified visual class, the status is _S_U_C_C_E_S_S. If the requested plane(s) have no visual of the requested class, but there is a normal planes visual of the requested class, then that is the visual and the status is _A_L_M_O_S_T. Otherwise, _s_e_t_V_i_s_u_a_l() sets the default visual, and returns _F_A_I_L_U_R_E. +o colors - is either _M_A_X__A_V_A_I_L_A_B_L_E__C_O_L_O_R_S or else the actual number of colors needed, not counting any transparent pixel. For example, most 2-bit overlays only have 3 colors (and one transparent pixel). 8-bit visuals have 256 colors, unless there is a transparent pixel. _s_e_t_V_i_s_u_a_l() tries to get a visual that supports at least the requested number of colors. If it can do that, the status is _S_U_C_C_E_S_S. Otherwise, it does the best it can and the status is _A_L_M_O_S_T. +o transparency - one of _T_R_A_N_S_P_A_R_E_N_T__N_O_N_E, _T_R_A_N_S_P_A_R_E_N_T__P_I_X_E_L, _T_R_A_N_S_P_A_R_E_N_T__M_A_S_K, or _T_R_A_N_S_P_A_R_E_N_T__D_O_N_T__C_A_R_E. +o forceNewCmap - If _f_o_r_c_e_N_e_w_C_m_a_p is true, you are guaranteed a new, empty, colormap. Otherwise, _V_k_V_i_s_u_a_l will reuse an existing colormap for this visual if one is available. Unless you know you need a new colormap, you should leave this _F_A_L_S_E. _s_e_t_V_i_s_u_a_l() tries to get a visual that supports the requested type of transparency. If it can, the status is success. Otherwise, it does the best it can and the status is _A_L_M_O_S_T. ssssttttaaaattttuuuussssSSSSttttrrrriiiinnnngggg(((()))) const char *statusString(status) const Debug function: print (on stderr) the string equivalent to the passed enum value. ttttrrrraaaannnnssssppppaaaarrrreeeennnnccccyyyySSSSttttrrrriiiinnnngggg(((()))) const char *transparencyString(transparency) const Debug function: print (on stderr) the string equivalent to the passed enum value. vvvviiiissssuuuuaaaallll(((()))) virtual Visual *visual() const PPPPaaaaggggeeee 11112222 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) Returns this instance's visual. vvvviiiissssuuuuaaaallllCCCCllllaaaassssssssSSSSttttrrrriiiinnnngggg(((()))) const char *visualClassString(int) const Debug function: print (on stderr) the string equivalent to the passed enum value ("Pseudocolor", etc). vvvviiiissssuuuuaaaallllIIIIDDDD(((()))) virtual VisualID visualID() const Returns the visual ID of this instance's visual. vvvviiiissssuuuuaaaallllPPPPaaaarrrreeeennnntttt(((()))) static Widget visualParent( Widget w, Visual ** ) Returns the first widget, higher in the widget tree, that has a visual attribute. Normally, this widget will be a subclass of _S_h_e_l_l, but it could be an _S_g_V_i_s_u_a_l_D_r_a_w_i_n_g_A_r_e_a or any other widget that has an _X_m_N_v_i_s_u_a_l resource. vvvviiiissssuuuuaaaallllPPPPaaaarrrreeeennnnttttAAAArrrrggggssss(((()))) static void visualParentArgs(Widget parent, Arg *args, int *cnt) This gets a set of visual resources, appropriate to the _p_a_r_e_n_t widget. The resources are copied into _a_r_g_s, and _c_n_t is updated. All resources except the visual are copied from the parent. Visual is copied from the _v_i_s_u_a_l_P_a_r_e_n_t(_p_a_r_e_n_t). vvvvkkkkVVVViiiissssuuuuaaaallllIIIInnnnffffoooo(((()))) virtual const VkVisualInfo *vkVisualInfo( VisualID vid) const Returns a pointer to the _V_k_V_i_s_u_a_l_I_n_f_o structure associated with the visual whose ID is _v_i_d. vvvvkkkkVVVViiiissssuuuuaaaallllIIIInnnnffffoooo(((()))) virtual const VkVisualInfo *vkVisualInfo( Visual *vis=_N_U_L_L) const Returns a pointer to the _V_k_V_i_s_u_a_l_I_n_f_o structure associated with the specified visual. If _v_i_s is _N_U_L_L, the current visual is used. vvvvkkkkVVVViiiissssuuuuaaaallllIIIInnnnffffoooo(((()))) virtual const VkVisualInfo *vkVisualInfo( Widget w) const PPPPaaaaggggeeee 11113333 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) Returns a pointer to the _V_k_V_i_s_u_a_l_I_n_f_o structure associated with the widget's visual. vvvvkkkkVVVViiiissssuuuuaaaallllIIIInnnnffffoooo(((()))) virtual const VkVisualInfo *vkVisualInfo( int index ) const Returns a pointer to one of the _V_k_V_i_s_u_a_l_I_n_f_o structures from the global list maintained by _V_k_V_i_s_u_a_l. Possible arguments are: <<<<nnnnuuuummmmbbbbeeeerrrr>>>> - an integer from 0 to the number of available visuals retrieve a pointer to that _V_k_V_i_s_u_a_l_I_n_f_o structure. RRRREEEESSSSEEEETTTT - resets the global record so that a call to _v_k_V_i_s_u_a_l_I_n_f_o(_N_E_X_T) _w_i_l_l _r_e_t_u_r_n _a _p_o_i_n_t_e_r _t_o _t_h_e _f_i_r_s_t _s_t_r_u_c_t_u_r_e. _R_e_t_u_r_n_s _N_U_L_L. FFFFIIIIRRRRSSSSTTTT - returns a pointer to the first structure. NNNNEEEEXXXXTTTT - returns a pointer to the first structure beyond the previously retrieved one, regardless of how it was retrieved. If the previously retrieved structure was the last structure, a _R_E_S_E_T is done and a _N_U_L_L pointer is returned. The next _v_k_V_i_s_u_a_l_I_n_f_o(_N_E_X_T) _c_a_l_l _w_i_l_l _r_e_t_r_i_e_v_e (_a _p_o_i_n_t_e_r _t_o) _t_h_e _f_i_r_s_t _s_t_r_u_c_t_u_r_e. LLLLAAAASSSSTTTT - returns a pointer to the last structure. wwwwiiiinnnnddddoooowwww(((()))) virtual Window window() const Returns a window associated with this instance's visual. VkApp's window is used for that visual. The root window is used for its visual. For any other X11 visual, a matching new _I_n_p_u_t_O_u_t_p_u_t unmapped window will be created the first time a window is needed for that particular visual. Windows will reused later as necessary. Separate VkVisual instances will return the same window if the instances are for the same X11 visual. Note that there is no guarantee as to which window you will get back, even if you used the _V_k_V_i_s_u_a_l(_w_i_d_g_e_t) constructor. Typical use of this window is as a parameter to create a GC or to call the Xpm pixmaps routines (which derive visual information from the window they are passed). Because a window may be re-used, it is important that the application not delete it. PPPPaaaaggggeeee 11114444 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) EEEExxxxaaaammmmpppplllleeeessss ooooffff PPPPuuuuttttttttiiiinnnngggg AAAA WWWWiiiiddddggggeeeetttt IIIInnnn AAAA NNNNoooonnnn----DDDDeeeeffffaaaauuuulllltttt VVVViiiissssuuuuaaaallll 1) Using _V_k_V_i_s_u_a_l, putting a single widget in a non-default visual is very straight-forward. Widget p; // Parent widget char *c="Questions"; // Widget's name ... _V_k_V_i_s_u_a_l vis(p); // Get the visual info XmCreateQuestionDialog (p, c, vis.argList(), vis.argCnt()); ... _2) Putting your entire application into a non-default visual is only a little more complicated. See _V_k_A_p_p(_3_X). 3) Creating a GC of the right depth: Display *dpy; _V_k_V_i_s_u_a_l vis(widget); ... XCreateGC ( dpy, vis.window(), .... ) RRRREEEEVVVVIIIIEEEEWWWW OOOOFFFF XXXX11111111 VVVVIIIISSSSUUUUAAAALLLL IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN Many developers do not quite understand how X and Xt deal with information that is related to X11 visuals. This information is important if one is going to put part or all of an application's GUI in a non-default visual. Following is a summary of some of the more important points. XXXX11111111 VVVViiiissssuuuuaaaallll AAAAttttttttrrrriiiibbbbuuuutttteeeessss X11 does not attach any semantic meaning to a visual. For example, there is no concept of an "overlay visual". There is, however, a semi-standard convention that has been adopted by SGI and by some other workstation vendors: +o A visual's _l_e_v_e_l is the framebuffer level the visual is associated with. This is a hardware-related term. It has nothing to do with X window stacking order. +o Levels less than zero are underlays. As of this writing (8/96), SGI has no hardware that has underlay planes that are supported by the X server. +o Level zero is the normal planes. The _d_e_f_a_u_l_t _v_i_s_u_a_l is generally (but not necessarily) in the normal planes. PPPPaaaaggggeeee 11115555 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) +o Levels greater than zero are overlay planes. +o Each X11 visual is associated with exactly one _l_e_v_e_l. +o _S_E_R_V_E_R__O_V_E_R_L_A_Y__V_I_S_U_A_L_S is a property on the root window, relating each X11 visual to its _l_e_v_e_l. An X11 window has several attributes that need to be consistent when the window is created. If an application sets these values inconsistently, or if it allows an inconsistent value to be inherited, the X server will return a fatal BBBBaaaaddddMMMMaaaattttcccchhhh error. +o _X_C_r_e_a_t_e_W_i_n_d_o_w(_3_X) must be passed a consistent visual and depth. +o Certain fields in the _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s structure that is passed to _X_C_r_e_a_t_e_W_i_n_d_o_w(_3_X) must be consistent with the visual and depth. The significant fields are: _b_a_c_k_g_r_o_u_n_d _p_i_x_m_a_p - must be _N_U_L_L or of the stated depth. _b_a_c_k_g_r_o_u_n_d _p_i_x_e_l - is used if the background pixmap is _N_U_L_L. The pixel value must not exceed the colormap size. _b_o_r_d_e_r _p_i_x_m_a_p - must be _N_U_L_L or of the stated depth. _b_o_r_d_e_r _p_i_x_e_l - is used if the border pixmap is _N_U_L_L. The pixel value must not exceed the colormap size. _c_o_l_o_r_m_a_p - must match the visual. The depth and visual cannot be changed after the window is created. The _X_S_e_t_W_i_n_d_o_w_A_t_t_r_i_b_u_t_e_s values can be changed later. XXXXtttt VVVViiiissssuuuuaaaallll HHHHaaaannnnddddlllliiiinnnngggg Xt does not make it easy to achieve the required consistency when dealing with widgets in non-default visuals. Under the Xt widget model: +o A gadget does not have any visual resources of its own, because it draws into its parent's window. +o Each widget class, because it is derived from the _C_o_r_e class, has _b_o_r_d_e_r_P_i_x_m_a_p, _b_o_r_d_e_r_C_o_l_o_r, _c_o_l_o_r_m_a_p, and _d_e_p_t_h attributes. Each widget instance inherits the values of these attributes from its parent widget. PPPPaaaaggggeeee 11116666 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) +o If a widget does not have an _X_m_N_v_i_s_u_a_l resource, its visual cannot be explicitly set at creation time. Most widgets do not have a visual resource, so they _m_u_s_t inherit their visual. The only way these widgets can be put into a non-default visual is for their widget parent to be in that visual. +o The only standard widgets that have an _X_m_N_v_i_s_u_a_l resource (and hence an X11 visual) directly associated with them are _S_h_e_l_l and its subclasses. (Note: there can also be special widgets, such as the _S_g_V_i_s_u_a_l_D_r_a_w_i_n_g_A_r_e_a widget ( <_S_g_m/_V_i_s_u_a_l_D_r_a_w_i_n_g_A._h> ), that have an associated X11 visual. Such special widgets are not common.) +o Any widget that does not have a visual resource explicitly set at creation time inherits its visual from its parent _w_i_n_d_o_w. For all widgets other than _S_h_e_l_l widgets, the parent window is the parent widget's window. This results in inheriting a consistent set of values, and there is no problem. However, the situation is different for a _S_h_e_l_l widget. Its parent window is the _r_o_o_t _w_i_n_d_o_w. Thus, if the parent widget is using a different visual than the root window's visual, you _m_u_s_t explicitly set at least some of the _S_h_e_l_l's visual resources. If you do not, you will get an X server BBBBaaaaddddMMMMaaaattttcccchhhh fatal error. To avoid mismatches, ViewKit explicitly sets the visual information for all new _S_h_e_l_l widgets it creates. This includes all menus and dialogs. _S_h_e_l_l visual attributes are set to, in priority order: +o If visual information is passed in by the application, it is used. +o If the widget is a menu, and _u_s_e_O_v_e_r_l_a_y_M_e_n_u_s is set, an appropriate visual is chosen. +o If the widget is a dialog, and _u_s_e_O_v_e_r_l_a_y_D_i_a_l_o_g_s is set, an appropriate visual is chosen. +o Otherwise ViewKit sets the _S_h_e_l_l (i.e. menu or dialog) to the widget parent's visual. The net effect is that most ViewKit applications do not need to worry about this. It is possible to place the top shell (VkApp's unrealized shell) in a non-default visual. Because of the inheritance described above, That effectively resets the visual for the rest of the application. (See _V_k_A_p_p(_3_X), topics _u_s_e_O_v_e_r_l_a_y_A_p_p_s() and _p_r_e_R_e_a_l_i_z_e_F_u_n_c_t_i_o_n(). PPPPaaaaggggeeee 11117777 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) Visual consistency issues are important when creating _S_h_e_l_l widgets. They are also important at other times. For example, you cannot use a pixmap or a GC at a depth other than the one it was created for. CCCCoooolllloooorrrrmmmmaaaappppssss Pixel values need to be kept consistent. In general, the same pixel will not be the same color in the various colormaps. Be sure you use the correct pixel value for the current colormap. The BlackPixel and WhitePixel macros should be avoided. They do as X11 documents and return pixel values suitable for use with the _d_e_f_a_u_l_t colormap. BlackPixel returns a pixel which is black in the normal planes colormaps, but is generally transparent in overlay colormaps. Another common way to get inconsistent pixel values is for an application to determine a pixel value using the default colormap, and then to use it in a different colormap. If the pixel exists, you are likely to get the wrong color. If the pixel does not exist (such as when you try to apply a pixel greater than 3 to a 2-bit overlay colormap), you will get an X protocol error. If you do decide to put widgets in one of the overlay visuals, remember that the colormap may well be smaller than the default one. And don't forget that pixel 0 is apt to be transparent. Some hardware has a 2-bit level 1 visual, a 2-bit level 2 visual, and a 4-bit level 1 visual that are not entirely independent. The two-bit colormaps will be independent, but they may overlap with the 4-bit colormap. The framebuffer pixels of the 4-bit visual may overlap with those of the 2-bit visuals. On such hardware, using the 4-bit visual is discouraged. CCCCoooolllloooorrrrmmmmaaaapppp CCCCoooooooorrrrddddiiiinnnnaaaattttiiiioooonnnn There is no such thing as a system default colormap for any visual other than the default visual. If a _V_k_V_i_s_u_a_l instance refers to the default visual, it automatically uses the default colormap. The first _V_k_V_i_s_u_a_l instance that refers to each non-default visual creates a suitable colormap for that visual. Subsequent _V_k_V_i_s_u_a_l instances that refer to the same visual re-use the colormap the first instance created. This effectively establishes default colormaps for a single application. There is no supported way for multiple independent applications to cooperate on using a common colormap. If we get to where there is a default colormap for the various visuals, _V_k_V_i_s_u_a_l will provide it. An application is only guaranteed to have its colormaps installed when it has colormap focus. Consequently, there may be colormap flashing. When an application gets colormap focus, all of the colormaps the application has declared get installed (whether or not it actually needs them). These colormaps remain until another application needs to have one of PPPPaaaaggggeeee 11118888 _V_k_V_i_s_u_a_l((((3333xxxx)))) _V_k_V_i_s_u_a_l((((3333xxxx)))) them replaced. Any of your application's windows that need a conflicting colormap will not return to correct colors until your application next gets colormap focus. +o Override widgets (e.g. pull-down and popup menus) are responsible for installing their own colormaps. They will not get their colormaps installed - ever - unless the application does something about it. +o Likewise, overlay dialogs will not get their color maps installed until the dialog gets colormap focus. +o ViewKit arranges automatic installation of colormaps for the menu and dialog widgets it creates. Otherwise you must call XSetWMColormapWindows() yourself. KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS Any ViewKit class that puts up any kind of a _S_h_e_l_l widget uses this class. That includes _V_k_A_p_p, _V_k_S_i_m_p_l_e_W_i_n_d_o_w, _V_k_F_i_l_e_S_e_t, _V_k_G_r_a_p_h, _V_k_I_c_o_n_B_u_t_t_o_n, _V_k_M_e_t_e_r, _V_k_O_u_t_l_i_n_e, _V_k_H_e_l_p_A_P_I, the _V_k_I_c_o_n* and _V_k_P_i_x_m_a_p* classes, the dialog classes, and the menu classes. SSSSEEEEEEEE AAAALLLLSSSSOOOO _V_k_A_p_p(_3), _V_k_D_i_a_l_o_g_M_a_n_a_g_e_r(_3), _V_k_M_e_n_u (_3), _V_k_S_i_m_p_l_e_W_i_n_d_o_w(_3), _V_k_S_u_b_M_e_n_u (_3) _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Scheifler and Jim Gettys _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick PPPPaaaaggggeeee 11119999